<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Put snapshot repository API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'put-snapshot-repo-api.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/put-snapshot-repo-api.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/put-snapshot-repo-api.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/put-snapshot-repo-api.html" rel="nofollow" target="_blank">../en/put-snapshot-repo-api.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="snapshot-restore-apis.html">Snapshot and restore APIs</a></span>
»
<span class="breadcrumb-node">Put snapshot repository API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="get-snapshot-repo-api.html">« Get snapshot repository API</a>
</span>
<span class="next">
<a href="verify-snapshot-repo-api.html">Verify snapshot repository API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="put-snapshot-repo-api"></a>Put snapshot repository API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Registers or updates a <a class="xref" href="snapshots-register-repository.html" title="Register a snapshot repository">snapshot repository</a>.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_repository
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2140.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-snapshot-repo-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">PUT /_snapshot/&lt;repository&gt;</code></p>
<p><code class="literal">POST /_snapshot/&lt;repository&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-snapshot-repo-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc">edit</a>
</h3>
</div></div></div>
<p>A snapshot repository must be registered before you can perform
<a class="xref" href="snapshot-restore.html" title="Snapshot and restore">snapshot and restore</a> operations. You can use the put
snapshot repository API to register new repositories and update existing ones.
See <a class="xref" href="snapshots-register-repository.html" title="Register a snapshot repository"><em>Register repository</em></a>.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>Because snapshot formats can change between major versions of
Elasticsearch, we recommend registering a new snapshot repository for each major version.
See <a class="xref" href="snapshot-restore.html#snapshot-restore-version-compatibility" title="Version compatibility">Version compatibility</a>.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-snapshot-repo-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;repository&gt;</code>
</span>
</dt>
<dd>
(Required, string)
Name of the snapshot repository to register or update.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-snapshot-repo-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Several options for this API can be specified using a query parameter
or a request body parameter. If both parameters are specified, only the query
parameter is used.</p>
</div>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">verify</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean)
If <code class="literal">true</code>, the request verifies the repository is functional on all master and
data nodes in the cluster. If <code class="literal">false</code>, this verification is skipped. Defaults to
<code class="literal">true</code>.
</p>
<p>You can manually perform this verification using the
<a class="xref" href="verify-snapshot-repo-api.html" title="Verify snapshot repository API">verify snapshot repository API</a>.</p>
</dd>
</dl>
</div>
</div>

<div class="section child_attributes">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-snapshot-repo-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<a id="put-snapshot-repo-api-request-type"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">type</code>
</span>
</dt>
<dd>
<p>(Required, string)
Repository type.</p>
<details open>
<summary class="title">Valid values for <code class="literal">type</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">fs</code>
</span>
</dt>
<dd>
<p>
Shared file system repository. Repositories of this type use a shared file
system to store snapshots. This file system must accessible to all master and
data nodes in the cluster.
</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>To register a shared file system repository, you must mount the same
shared filesystem to the same location on all master and data nodes. This
location must be registered in the <code class="literal">path.repo</code> setting on all master and data
nodes in the cluster.</p>
</div>
</div>
<p>See <a class="xref" href="snapshots-register-repository.html#snapshots-filesystem-repository" title="Shared file system repository">Shared file system repository</a>.</p>
</dd>
<dt>
<span class="term">
<span class="xpack"><code class="literal">source</code></span><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</span>
</dt>
<dd>
<p>
Source-only repository. You can use source-only repositories to create minimal,
source-only snapshots that take up to 50% less space on disk.
</p>
<p>Source-only snapshots are only supported if the <a class="xref" href="mapping-source-field.html" title="_source field"><code class="literal">_source</code>
field</a> is enabled and no
<a class="xref" href="run-a-search.html#source-filtering" title="Source filtering">source-filtering</a> is applied.</p>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>Source-only snapshots contain stored fields and index metadata. They do
not include index or doc values structures and are not searchable when restored.
After restoring a source-only snapshot, you must <a class="xref" href="docs-reindex.html" title="Reindex API">reindex</a> the
data into a new index.</p>
</div>
</div>
<p>See <a class="xref" href="snapshots-register-repository.html#snapshots-source-only-repository" title="Source only repository">Source only repository</a>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">url</code>
</span>
</dt>
<dd>
<p>
URL repository. Repositories of this type are read-only
for the cluster. This means the cluster can retrieve or restore snapshots from
the repository but cannot write or create snapshots in it.
</p>
<p>You can use URL repositories as an alternative way to give a cluster read-only
access to a shared file system (<code class="literal">fs</code>) repository.</p>
<p>See <a class="xref" href="snapshots-register-repository.html#snapshots-read-only-repository" title="Read-only URL repository">Read-only URL repository</a>.</p>
</dd>
</dl>
</div>
</div>
</details>
<p>More repository types are available through these official
plugins:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-s3.html" class="ulink" target="_top">repository-s3</a> for S3 repository support
</li>
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-hdfs.html" class="ulink" target="_top">repository-hdfs</a> for HDFS repository support in
Hadoop environments
</li>
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-azure.html" class="ulink" target="_top">repository-azure</a> for Azure storage
repositories
</li>
<li class="listitem">
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/repository-gcs.html" class="ulink" target="_top">repository-gcs</a> for Google Cloud Storage
repositories
</li>
</ul>
</div>
</dd>
</dl>
</div>
<div class="variablelist">
<a id="put-snapshot-repo-api-settings-param"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">settings</code>
</span>
</dt>
<dd>
<p>(Required, object)
Contains settings for the repository.</p>
<p>The following <code class="literal">settings</code> properties are valid for all repository types:</p>
<details open>
<summary class="title">Properties of <code class="literal">settings</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">chunk_size</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#byte-units" title="Byte size units">byte value</a>)
Maximum size of files in snapshots. In snapshots, files larger than this are
broken down into chunks of this size or smaller. Defaults to <code class="literal">null</code> (unlimited
file size).
</dd>
<dt>
<span class="term">
<code class="literal">compress</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>, metadata files, such as index mappings and settings, are compressed
in snapshots. Data files are not compressed. Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">max_restore_bytes_per_sec</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#byte-units" title="Byte size units">byte value</a>)
Maximum snapshot restore rate per node. Defaults to <code class="literal">40mb</code> per second.
</dd>
<dt>
<span class="term">
<code class="literal">max_snapshot_bytes_per_sec</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#byte-units" title="Byte size units">byte value</a>)
Maximum snapshot creation rate per node. Defaults to <code class="literal">40mb</code> per second.
</dd>
<dt>
<span class="term">
<code class="literal">readonly</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean)
If <code class="literal">true</code>, the repository is read-only. The cluster can retrieve and restore
snapshots from the repository but not write to the repository or create
snapshots in it.
</p>
<p>If <code class="literal">false</code>, the cluster can write to the repository and create snapshots in it.
Defaults to <code class="literal">false</code>.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you register the same snapshot repository with multiple clusters, only
one cluster should have write access to the repository. Having multiple clusters
write to the repository at the same time risks corrupting the contents of the
repository.</p>
<p>Only a cluster with write access can create snapshots in the repository. All
other clusters connected to the repository should have the <code class="literal">readonly</code> parameter
set to <code class="literal">true</code>. This means those clusters can retrieve or restore snapshots from
the repository but not create snapshots in it.</p>
</div>
</div>
</dd>
</dl>
</div>
</div>
</details>
<p>Other accepted <code class="literal">settings</code> properties depend on the repository type, set using the
<a class="xref" href="put-snapshot-repo-api.html#put-snapshot-repo-api-request-type"><code class="literal">type</code></a> parameter.</p>
<details open>
<summary class="title">Valid <code class="literal">settings</code> properties for <code class="literal">fs</code> repositories</summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">location</code>
</span>
</dt>
<dd>
(Required, string)
Location of the shared filesystem used to store and retrieve snapshots. This
location must be registered in the <code class="literal">path.repo</code> setting on all master and data
nodes in the cluster.
</dd>
</dl>
</div>
</div>
</details>
<details open>
<summary class="title">Valid <code class="literal">settings</code> properties for <code class="literal">source</code> repositories</summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">delegate_type</code>
</span>
</dt>
<dd>
<p>
(Optional, string)
Delegated repository type. For valid values, see the
<a class="xref" href="put-snapshot-repo-api.html#put-snapshot-repo-api-request-type"><code class="literal">type</code> parameter</a>.
</p>
<p><code class="literal">source</code> repositories can use <code class="literal">settings</code> properties for its delegated repository
type. See <a class="xref" href="snapshots-register-repository.html#snapshots-source-only-repository" title="Source only repository">Source only repository</a>.</p>
</dd>
</dl>
</div>
</div>
</details>
<details open>
<summary class="title">Valid <code class="literal">settings</code> properties for <code class="literal">url</code> repositories</summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">url</code>
</span>
</dt>
<dd>
<p>
(Required, string)
URL location of the root of the shared filesystem repository. The following
protocols are supported:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">file</code>
</li>
<li class="listitem">
<code class="literal">ftp</code>
</li>
<li class="listitem">
<code class="literal">http</code>
</li>
<li class="listitem">
<code class="literal">https</code>
</li>
<li class="listitem">
<code class="literal">jar</code>
</li>
</ul>
</div>
</dd>
</dl>
</div>
<p>URLs using the <code class="literal">file</code> protocol must point to the location of a shared filesystem
accessible to all master and data nodes in the cluster. This location must be
registered in the <code class="literal">path.repo</code> setting.</p>
<p>URLs using the <code class="literal">http</code>, <code class="literal">https</code>, or <code class="literal">ftp</code> protocols must be explicitly allowed with the
<code class="literal">repositories.url.allowed_urls</code> setting. This setting supports wildcards in the
place of a host, path, query, or fragment in the URL.</p>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">verify</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean)
If <code class="literal">true</code>, the request verifies the repository is functional on all master and
data nodes in the cluster. If <code class="literal">false</code>, this verification is skipped. Defaults to
<code class="literal">true</code>.
</p>
<p>You can manually perform this verification using the
<a class="xref" href="snapshots-register-repository.html#snapshots-repository-verification" title="Repository verification">verify snapshot repository API</a>.</p>
</dd>
</dl>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="get-snapshot-repo-api.html">« Get snapshot repository API</a>
</span>
<span class="next">
<a href="verify-snapshot-repo-api.html">Verify snapshot repository API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>